Wheel Dağıtım Formatı: Python için İkili Paketler Oluşturmak

Python ekosistemi, verimli paket yönetimine büyük ölçüde bağlıdır. Bu ekosistemin temel taşlarından biri, genellikle .whl uzantısı ile tanımlanan Wheel dağıtım formatıdır. Bu rehber, Wheel formatının inceliklerini, avantajlarını ve Python için nasıl ikili paketler oluşturulacağını inceleyerek, sorunsuz ve güvenilir yazılım dağıtımı hedefleyen global geliştiricilere hitap etmektedir.

Wheel Formatı Nedir?

Wheel formatı, Python için oluşturulmuş bir paket formatıdır. Kaynak dağıtımlarından (sdist) daha kolay kurulacak şekilde tasarlanmıştır. Eski egg formatının yerini alarak, onun bazı eksikliklerini gidermektedir. Esasen, pip ve diğer kurulum araçlarının paketi kaynaktan oluşturmasına gerek kalmadan hızlı bir şekilde kurmasını sağlayan, belirli bir yapıya ve meta verilere sahip bir ZIP arşividir.

Wheel'in Temel Özellikleri

• Platform Bağımsızlığı (uygun olduğunda): Wheel'ler, belirli platformlar ve mimariler (örneğin, Windows 64-bit, Linux x86_64) için veya platformdan bağımsız (saf Python) olarak oluşturulabilir. Bu, farklı işletim sistemleri için optimize edilmiş ikililerin oluşturulmasına olanak tanır.
• Kolay Kurulum: Wheel formatı, önceden oluşturulmuş dağıtımlar içerir ve kurulum sırasında kod derleme ihtiyacını en aza indirir. Bu, özellikle C uzantıları veya diğer derlenmiş bileşenleri olan paketler için kurulum sürecini önemli ölçüde hızlandırır.
• Meta Veri Dahil Etme: Wheel'ler, bağımlılıklar, sürüm bilgileri ve giriş noktaları dahil olmak üzere paket hakkında gerekli tüm meta verileri içerir. Bu meta veriler, pip gibi paket yöneticilerinin bağımlılıkları yönetmesi ve paketi doğru şekilde kurması için çok önemlidir.
• Atomik Kurulum: pip, Wheel'lerden paketleri atomik bir şekilde kurar. Bu, kurulumun ya tamamen başarılı olduğu ya da tamamen geri alındığı anlamına gelir, kısmen kurulan ve tutarsızlıklara yol açabilen paketlerin oluşmasını engeller.
• Tekrar Üretilebilirlik: Wheel'ler, yeniden derlemeye gerek kalmadan (hedef platformun eşleşmesi koşuluyla) birden fazla ortamda kurulabilen tutarlı bir yapı eseri sağlayarak tekrar üretilebilirliği artırır.

Neden Wheel Kullanmalısınız?

Kaynak dağıtımları yerine Wheel'leri seçmek, paket kurulum ve dağıtım sürecini kolaylaştırarak birçok avantaj sunar. İşte temel faydaların bir dökümü:

Daha Hızlı Kurulum Süreleri

Wheel'lerin en önemli avantajlarından biri hızlarıdır. Önceden oluşturulmuş dağıtımlar sağlayarak, Wheel'ler kurulum sırasında kod derleme ihtiyacını ortadan kaldırır. Bu, C, C++ veya diğer dillerde yazılmış derlenmiş uzantıları olan paketler için özellikle faydalıdır. Karmaşık bir bilimsel kütüphane dağıttığınızı düşünün; bir Wheel kullanmak, son kullanıcı makinelerinde kurulum süresini önemli ölçüde azaltır.

Örnek: numpy'ı kaynaktan kurmak, özellikle eski donanımlarda birkaç dakika sürebilir. Bir Wheel'den kurmak genellikle saniyeler sürer.

Derleme Araçlarına Bağımlılığı Azaltır

Paketleri kaynaktan kurmak, genellikle kullanıcıların sistemlerinde gerekli derleme araçlarına (derleyiciler, başlıklar vb.) sahip olmalarını gerektirir. Bu, özellikle yazılım geliştirmeye aşina olmayan kullanıcılar için bir engel olabilir. Wheel'ler bu bağımlılığı ortadan kaldırarak kurulumu daha basit ve erişilebilir hale getirir.

Örnek: Bir araştırma laboratuvarındaki bir veri bilimcisi, bir paketi kaynaktan oluşturmak için gerekli derleyicilere sahip olmayabilir. Bir Wheel, ortamlarını yapılandırmalarına gerek kalmadan paketi doğrudan kurmalarını sağlar.

Geliştirilmiş Güvenilirlik

Wheel'ler, önceden oluşturulmuş ikililer sağlayarak, paketin farklı ortamlarda tutarlı bir şekilde kurulmasını sağlar. Bu, sistem yapılandırmalarındaki veya derleme aracı sürümlerindeki farklılıklardan kaynaklanan kurulum hataları riskini azaltır. Bu tutarlılık, kararlı ve öngörülebilir davranış talep eden uygulamalar için çok önemlidir.

Örnek: Birden fazla sunucuya dağıtılan bir web uygulamasının tutarlı paket sürümlerine sahip olması gerekir. Wheel'ler kullanmak, her sunucuya aynı ikililerin kurulmasını sağlayarak dağıtım sorunları riskini en aza indirir.

Geliştirilmiş Güvenlik

Wheel'ler, kimliklerini ve bütünlüklerini doğrulamak için imzalanabilir. Bu, kötü niyetli aktörlerin kurcalanmış paketler dağıtmasını önlemeye yardımcı olur. Paket imzalama, kullanıcıların güvenilir yazılımlar kurduğundan emin olmak için ek bir güvenlik katmanı sağlar.

Örnek: Kuruluşlar, tüm paketlerin üretim ortamlarına dağıtılmadan önce imzalanmasını gerektiren politikalar uygulayabilir. Bu, kötü amaçlı kodun paketlere enjekte edildiği tedarik zinciri saldırılarına karşı koruma sağlar.

Wheel Paketleri Oluşturma: Adım Adım Kılavuz

Wheel paketleri oluşturmak, setuptools ve wheel paketlerini kullanmayı içeren basit bir işlemdir. İşte ayrıntılı bir kılavuz:

1. Projenizi Kurmak

İlk olarak, projenizin düzgün bir şekilde yapılandırıldığından emin olun. En azından, bir setup.py dosyasına ve paketin kaynak koduna ihtiyacınız olacak.

Proje Yapısı Örneği:

my_package/
 ├── my_module/
 │   ├── __init__.py
 │   └── my_function.py
 ├── setup.py
 └── README.md

2. setup.py Dosyası

setup.py dosyası, projenizin kalbidir. Paketiniz hakkındaki meta verileri içerir ve nasıl oluşturulması ve kurulması gerektiğini tanımlar. İşte bir setup.py dosyasına bir örnek:

from setuptools import setup, find_packages

setup(
 name='my_package',
 version='0.1.0',
 description='Basit bir örnek paket',
 long_description=open('README.md').read(),
 long_description_content_type='text/markdown',
 url='https://github.com/your_username/my_package',
 author='Adınız',
 author_email='your.email@example.com',
 license='MIT',
 packages=find_packages(),
 install_requires=['requests'],
 classifiers=[
 'Development Status :: 3 - Alpha',
 'Intended Audience :: Developers',
 'License :: OSI Approved :: MIT License',
 'Programming Language :: Python :: 3',
 'Programming Language :: Python :: 3.6',
 'Programming Language :: Python :: 3.7',
 'Programming Language :: Python :: 3.8',
 'Programming Language :: Python :: 3.9',
 ],
)

Temel Alanların Açıklaması:

• name: Paketinizin adı. Bu, kullanıcıların paketinizi kurmak için kullanacakları addır (örneğin, pip install my_package).
• version: Paketinizin sürüm numarası. Tutarlı sürümleme uygulamaları için semantik sürümlemeyi (SemVer) izleyin (örneğin, 0.1.0, 1.0.0, 2.5.1).
• description: Paketinizin kısa bir açıklaması.
• long_description: Paketinizin ayrıntılı bir açıklaması. Bu genellikle bir README.md dosyasından okunur.
• url: Paketinizin ana sayfasının veya deposunun URL'si.
• author: Paket yazarının adı.
• author_email: Paket yazarının e-posta adresi.
• license: Paketinizin dağıtıldığı lisans (örneğin, MIT, Apache 2.0, GPL).
• packages: Dağıtımınıza dahil edilecek paketlerin listesi. find_packages() projenizdeki tüm paketleri otomatik olarak bulur.
• install_requires: Paketinizin gerektirdiği bağımlılıkların listesi. pip, paketiniz kurulduğunda bu bağımlılıkları otomatik olarak kuracaktır.
• classifiers: Kullanıcıların paketinizi PyPI'de (Python Package Index) bulmasına yardımcı olan meta veriler. Bu sınıflandırıcılar, geliştirme durumunu, amaçlanan kitleyi, lisansı ve desteklenen Python sürümlerini açıklar.

3. wheel Kurulumu

wheel paketi kurulu değilse, pip kullanarak kurabilirsiniz:

pip install wheel

4. Wheel Paketini Oluşturmak

Projenizin kök dizinine (setup.py'nin bulunduğu yer) gidin ve aşağıdaki komutu çalıştırın:

python setup.py bdist_wheel

Bu komut, Wheel paketini (.whl dosyası) ve bir kaynak dağıtımı (.tar.gz dosyası) içeren bir dist dizini oluşturacaktır.

5. Wheel Dosyasını Bulma

Oluşturulan Wheel dosyası, dist dizininde bulunacaktır. Adı şu biçimde olacaktır: paket_adı-version-pyXX-none-any.whl, burada:

• paket_adı: Paketinizin adı.
• version: Paketinizin sürüm numarası.
• pyXX: Paketin uyumlu olduğu Python sürümü (örneğin, Python 3.7 için py37).
• none: Paketin platforma özgü olmadığını gösterir.
• any: Paketin herhangi bir mimariyle uyumlu olduğunu gösterir.

Platforma özgü wheel'ler için, none ve any etiketleri platform ve mimari tanımlayıcılarıyla değiştirilecektir (örneğin, Windows 64-bit için win_amd64).

6. Wheel Paketini Test Etmek

Wheel paketinizi dağıtmadan önce, doğru kurulduğundan emin olmak için test etmeniz önemlidir. Bunu pip kullanarak yapabilirsiniz:

pip install dist/my_package-0.1.0-py39-none-any.whl

dist/my_package-0.1.0-py39-none-any.whl'yi Wheel dosyanızın gerçek yoluyla değiştirin.

7. Wheel Paketinizi Dağıtmak

Wheel paketinizi oluşturup test ettikten sonra, çeşitli kanallar aracılığıyla dağıtabilirsiniz:

• PyPI (Python Package Index): Python paketlerini dağıtmanın en yaygın yolu. Wheel paketinizi twine kullanarak PyPI'ye yükleyebilirsiniz.
• Özel Paket Dizini: Bir kuruluş içinde dahili kullanım için, devpi veya Artifactory gibi araçları kullanarak özel bir paket dizini ayarlayabilirsiniz.
• Doğrudan Dağıtım: Wheel paketinizi ayrıca e-posta, dosya paylaşımı veya diğer yöntemlerle doğrudan kullanıcılara dağıtabilirsiniz.

C Uzantılarını ve Platforma Özgü Wheel'leri İşlemek

Platforma özgü Wheel'ler oluşturmak, özellikle C uzantıları içerenler, ek adımlar gerektirir. İşte sürecin genel bir görünümü:

1. C Uzantılarını Derlemek

C uzantılarının her hedef platform için derlenmesi gerekir. Bu genellikle bir C derleyicisi (örneğin, GCC, MSVC) ve platforma özgü derleme araçları kullanmayı içerir.

Örnek: Windows'ta, C uzantılarını oluşturmak için Microsoft Visual C++ derleyicisini kullanmanız gerekir. Linux'ta ise genellikle GCC kullanırsınız.

2. cffi veya Cython Kullanımı

cffi ve Cython gibi araçlar, C uzantıları oluşturma sürecini basitleştirebilir. cffi, C kodu yazmadan C kodunu doğrudan Python'dan çağırmanıza olanak tanırken, Cython, C uzantılarına derlenen C benzeri kod yazmanıza olanak tanır.

3. Platforma Özgü Bağımlılıkları Tanımlama

setup.py dosyanızda, setup_requires ve install_requires parametrelerini kullanarak platforma özgü bağımlılıklar tanımlayabilirsiniz. Bu, farklı platformlar için farklı bağımlılıklar belirtmenize olanak tanır.

Örnek:

from setuptools import setup, Extension
import platform

if platform.system() == 'Windows':
 extra_compile_args = ['/O2', '/EHsc']
else:
 extra_compile_args = ['-O3']

setup(
 name='my_package',
 version='0.1.0',
 ext_modules=[
 Extension(
 'my_package.my_extension',
 ['my_package/my_extension.c'],
 extra_compile_args=extra_compile_args,
 ),
 ],
)

4. Platforma Özgü Wheel'leri Oluşturmak

Platforma özgü Wheel'leri oluşturmak için, her bir hedef platform için uygun derleme ortamını kullanmanız gerekir. Bu, sanal makineler veya Docker gibi kapsayıcı teknolojilerini kullanmayı içerebilir.

Örnek: Windows 64-bit için bir Wheel oluşturmak için, derleme işlemini Microsoft Visual C++ derleyicisi kurulu olan bir Windows 64-bit sisteminde çalıştırmanız gerekir.

Wheel Paketi Oluşturma için En İyi Uygulamalar

En iyi uygulamaları takip etmek, Wheel paketlerinizin güvenilir, bakımı kolay ve kullanımı kolay olmasını sağlar. İşte bazı temel öneriler:

1. Semantik Sürümleme (SemVer) Kullanın

Tutarlı sürümleme uygulamaları için semantik sürümlemeyi (SemVer) takip edin. SemVer, her sürümdeki değişiklik türünü belirtmek için üç parçalı bir sürüm numarası (MAJOR.MINOR.PATCH) kullanır.

• MAJOR: Uyumsuz API değişikliklerini gösterir.
• MINOR: Geriye dönük uyumlu yeni özellikleri gösterir.
• PATCH: Geriye dönük uyumlu hata düzeltmelerini gösterir.

Örnek: Mevcut kodu bozan bir işlevin parametrelerini değiştirmek, büyük bir sürüm artışı gerektirir (örneğin, 1.0.0'dan 2.0.0'a). Mevcut olanları değiştirmeden yeni bir işlev eklemek, küçük bir sürüm artışı gerektirir (örneğin, 1.0.0'dan 1.1.0'a). Bir hatayı düzeltmek, bir yama sürümü artışı gerektirir (örneğin, 1.0.0'dan 1.0.1'e).

2. Bir README.md Dosyası Ekleyin

Paketinizin nasıl kullanılacağına dair kurulum talimatları, kullanım örnekleri ve katkı yönergeleri dahil ayrıntılı bir açıklama sağlayan bir README.md dosyası ekleyin. Bu, kullanıcıların paketinizi nasıl kullanacaklarını anlamalarına yardımcı olur ve katkıları teşvik eder.

3. Açık ve Öz Belgeler Yazın

API belgeleri, eğitimler ve örnekler dahil olmak üzere paketiniz için açık ve öz belgeler yazın. Kod yorumlarınızdan belgeler oluşturmak için Sphinx veya Read the Docs gibi araçları kullanın.

4. Bir Lisans Kullanın

Paketinizin, kullanılabileceği, değiştirilebileceği ve dağıtılabileceği koşulları açıkça tanımlayan bir lisans seçin. Yaygın lisanslar arasında MIT, Apache 2.0 ve GPL bulunur.

5. Paketinizi Kapsamlı Bir Şekilde Test Edin

pytest veya unittest gibi otomatik test araçlarını kullanarak paketinizi kapsamlı bir şekilde test edin. Paketinizi farklı senaryolarda doğru çalıştığından emin olmak için birim testleri, entegrasyon testleri ve uçtan uca testler yazın.

6. Sürekli Entegrasyonu (CI) Kullanın

Kod tabanında değişiklik yapıldığında paketinizi otomatik olarak oluşturmak ve test etmek için GitHub Actions, GitLab CI veya Jenkins gibi sürekli entegrasyon (CI) araçlarını kullanın. Bu, hataları erken yakalamanıza yardımcı olur ve paketinizin her zaman çalışır durumda olmasını sağlar.

7. Paketlerinizi İmzalayın

Paketlerinizin kimliğini ve bütünlüğünü doğrulamak için imzalayın. Bu, kötü niyetli aktörlerin kurcalanmış paketler dağıtmasını önlemeye yardımcı olur. Paketlerinizi imzalamak için gpg veya keyring gibi araçları kullanın.

Gelişmiş Wheel Teknikleri

Daha gelişmiş kullanım durumları için, bu teknikleri göz önünde bulundurun:

1. build Kullanımı

build paketi, Python paketlerini oluşturmanın modern ve standartlaştırılmış bir yolunu sağlar. Hem Wheel hem de kaynak dağıtımlarını destekler ve setuptools'tan daha basit bir arayüz sunar.

pip install build
python -m build

2. Düzenlenebilir Kurulumlar

Düzenlenebilir kurulumlar, bir paketi doğrudan kaynak koda bağlanan bir şekilde kurmanıza olanak tanır. Bu, kaynak kodundaki değişikliklerin, yeniden yüklemeye gerek kalmadan kurulu pakete hemen yansıdığı için geliştirme için kullanışlıdır.

pip install -e .

3. Derleme Sürecini Özelleştirme

Özel derleme komutları tanımlayarak veya Meson veya CMake gibi derleme sistemlerini kullanarak derleme sürecini özelleştirebilirsiniz. Bu, belirli derleyici bayraklarıyla C uzantıları oluşturmak veya harici kitaplıklara bağlamak gibi daha karmaşık derleme senaryolarını işlemenize olanak tanır.

4. auditwheel Kullanımı

auditwheel aracı, paylaşımlı kitaplıklar içeren Linux Wheel'lerini denetlemek ve onarmak için kullanılır. Wheel'in çok çeşitli Linux dağıtımlarında çalışması için gerekli tüm bağımlılıkları içerdiğinden emin olur.

pip install auditwheel
auditwheel repair dist/my_package-0.1.0-py39-linux_x86_64.whl

Sonuç

Wheel dağıtım formatı, verimli, güvenilir ve güvenli paket dağıtımı hedefleyen Python geliştiricileri için temel bir araçtır. Bu kılavuzda özetlenen adımları izleyerek ve en iyi uygulamaları benimseyerek, kurulum sürecini kolaylaştıran, derleme araçlarına olan bağımlılığı azaltan ve genel kullanıcı deneyimini iyileştiren Wheel paketleri oluşturabilirsiniz. Paketleri açık kaynak topluluğuna dağıtıyor veya dahili uygulamalar dağıtıyor olsanız da, Wheel formatını anlamak ve kullanmak, herhangi bir Python geliştiricisi için değerli bir beceridir. Python gelişmeye devam ettikçe, Wheel gibi modern paketleme uygulamalarını benimsemek, projelerinizin küresel bir kitle için erişilebilir ve sürdürülebilir kalmasını sağlar.

Bu uygulamaları benimseyerek, dünya çapında daha sağlam ve erişilebilir bir Python ekosistemine katkıda bulunursunuz.